home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / zggsvd.z / zggsvd
Text File  |  1996-03-14  |  9KB  |  265 lines
  1.  
  2.  
  3.  
  4. ZZZZGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))                                                          ZZZZGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZGGSVD - compute the generalized singular value decomposition (GSVD) of
  10.      an M-by-N complex matrix A and P-by-N complex matrix B
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE ZGGSVD( JOBU, JOBV, JOBQ, M, N, P, K, L, A, LDA, B, LDB,
  14.                         ALPHA, BETA, U, LDU, V, LDV, Q, LDQ, WORK, RWORK,
  15.                         IWORK, INFO )
  16.  
  17.          CHARACTER      JOBQ, JOBU, JOBV
  18.  
  19.          INTEGER        INFO, K, L, LDA, LDB, LDQ, LDU, LDV, M, N, P
  20.  
  21.          INTEGER        IWORK( * )
  22.  
  23.          DOUBLE         PRECISION ALPHA( * ), BETA( * ), RWORK( * )
  24.  
  25.          COMPLEX*16     A( LDA, * ), B( LDB, * ), Q( LDQ, * ), U( LDU, * ), V(
  26.                         LDV, * ), WORK( * )
  27.  
  28. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  29.      ZGGSVD computes the generalized singular value decomposition (GSVD) of an
  30.      M-by-N complex matrix A and P-by-N complex matrix B:
  31.  
  32.            U'*A*Q = D1*( 0 R ),    V'*B*Q = D2*( 0 R )
  33.  
  34.      where U, V and Q are unitary matrices, and Z' means the conjugate
  35.      transpose of Z.  Let K+L = the effective numerical rank of the matrix
  36.      (A',B')', then R is a (K+L)-by-(K+L) nonsingular upper triangular matrix,
  37.      D1 and D2 are M-by-(K+L) and P-by-(K+L) "diagonal" matrices and of the
  38.      following structures, respectively:
  39.  
  40.      If M-K-L >= 0,
  41.  
  42.                          K  L
  43.             D1 =     K ( I  0 )
  44.                      L ( 0  C )
  45.                  M-K-L ( 0  0 )
  46.  
  47.                        K  L
  48.             D2 =   L ( 0  S )
  49.                  P-L ( 0  0 )
  50.  
  51.                      N-K-L  K    L
  52.        ( 0 R ) = K (  0   R11  R12 )
  53.                  L (  0    0   R22 )
  54.      where
  55.  
  56.        C = diag( ALPHA(K+1), ... , ALPHA(K+L) ),
  57.        S = diag( BETA(K+1),  ... , BETA(K+L) ),
  58.        C**2 + S**2 = I.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))                                                          ZZZZGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))
  71.  
  72.  
  73.  
  74.        R is stored in A(1:K+L,N-K-L+1:N) on exit.
  75.  
  76.      If M-K-L < 0,
  77.  
  78.                        K M-K K+L-M
  79.             D1 =   K ( I  0    0   )
  80.                  M-K ( 0  C    0   )
  81.  
  82.                          K M-K K+L-M
  83.             D2 =   M-K ( 0  S    0  )
  84.                  K+L-M ( 0  0    I  )
  85.                    P-L ( 0  0    0  )
  86.  
  87.                         N-K-L  K   M-K  K+L-M
  88.        ( 0 R ) =     K ( 0    R11  R12  R13  )
  89.                    M-K ( 0     0   R22  R23  )
  90.                  K+L-M ( 0     0    0   R33  )
  91.  
  92.      where
  93.  
  94.        C = diag( ALPHA(K+1), ... , ALPHA(M) ),
  95.        S = diag( BETA(K+1),  ... , BETA(M) ),
  96.        C**2 + S**2 = I.
  97.  
  98.        (R11 R12 R13 ) is stored in A(1:M, N-K-L+1:N), and R33 is stored
  99.        ( 0  R22 R23 )
  100.        in B(M-K+1:L,N+M-K-L+1:N) on exit.
  101.  
  102.      The routine computes C, S, R, and optionally the unitary
  103.      transformation matrices U, V and Q.
  104.  
  105.      In particular, if B is an N-by-N nonsingular matrix, then the GSVD of A
  106.      and B implicitly gives the SVD of A*inv(B):
  107.                           A*inv(B) = U*(D1*inv(D2))*V'.
  108.      If ( A',B')' has orthnormal columns, then the GSVD of A and B is also
  109.      equal to the CS decomposition of A and B. Furthermore, the GSVD can be
  110.      used to derive the solution of the eigenvalue problem:
  111.                           A'*A x = lambda* B'*B x.
  112.      In some literature, the GSVD of A and B is presented in the form
  113.                       U'*A*X = ( 0 D1 ),   V'*B*X = ( 0 D2 )
  114.      where U and V are orthogonal and X is nonsingular, and D1 and D2 are
  115.      ``diagonal''.  The former GSVD form can be converted to the latter form
  116.      by taking the nonsingular matrix X as
  117.  
  118.                            X = Q*(  I   0    )
  119.                                  (  0 inv(R) )
  120.  
  121.  
  122. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  123.      JOBU    (input) CHARACTER*1
  124.              = 'U':  Unitary matrix U is computed;
  125.              = 'N':  U is not computed.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ZZZZGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))                                                          ZZZZGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))
  137.  
  138.  
  139.  
  140.      JOBV    (input) CHARACTER*1
  141.              = 'V':  Unitary matrix V is computed;
  142.              = 'N':  V is not computed.
  143.  
  144.      JOBQ    (input) CHARACTER*1
  145.              = 'Q':  Unitary matrix Q is computed;
  146.              = 'N':  Q is not computed.
  147.  
  148.      M       (input) INTEGER
  149.              The number of rows of the matrix A.  M >= 0.
  150.  
  151.      N       (input) INTEGER
  152.              The number of columns of the matrices A and B.  N >= 0.
  153.  
  154.      P       (input) INTEGER
  155.              The number of rows of the matrix B.  P >= 0.
  156.  
  157.      K       (output) INTEGER
  158.              L       (output) INTEGER On exit, K and L specify the dimension
  159.              of the subblocks described in Purpose.  K + L = effective
  160.              numerical rank of (A',B')'.
  161.  
  162.      A       (input/output) COMPLEX*16 array, dimension (LDA,N)
  163.              On entry, the M-by-N matrix A.  On exit, A contains the
  164.              triangular matrix R, or part of R.  See Purpose for details.
  165.  
  166.      LDA     (input) INTEGER
  167.              The leading dimension of the array A. LDA >= max(1,M).
  168.  
  169.      B       (input/output) COMPLEX*16 array, dimension (LDB,N)
  170.              On entry, the P-by-N matrix B.  On exit, B contains part of the
  171.              triangular matrix R if M-K-L < 0.  See Purpose for details.
  172.  
  173.      LDB     (input) INTEGER
  174.              The leading dimension of the array B. LDB >= max(1,P).
  175.  
  176.      ALPHA   (output) DOUBLE PRECISION array, dimension (N)
  177.              BETA    (output) DOUBLE PRECISION array, dimension (N) On exit,
  178.              ALPHA and BETA contain the generalized singular value pairs of A
  179.              and B; ALPHA(1:K) = 1,
  180.              BETA(1:K)  = 0, and if M-K-L >= 0, ALPHA(K+1:K+L) = C,
  181.              BETA(K+1:K+L)  = S, or if M-K-L < 0, ALPHA(K+1:M)= C,
  182.              ALPHA(M+1:K+L)= 0
  183.              BETA(K+1:M) = S, BETA(M+1:K+L) = 1 and ALPHA(K+L+1:N) = 0
  184.              BETA(K+L+1:N)  = 0
  185.  
  186.      U       (output) COMPLEX*16 array, dimension (LDU,M)
  187.              If JOBU = 'U', U contains the M-by-M unitary matrix U.  If JOBU =
  188.              'N', U is not referenced.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ZZZZGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))                                                          ZZZZGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))
  203.  
  204.  
  205.  
  206.      LDU     (input) INTEGER
  207.              The leading dimension of the array U. LDU >= max(1,M) if JOBU =
  208.              'U'; LDU >= 1 otherwise.
  209.  
  210.      V       (output) COMPLEX*16 array, dimension (LDV,P)
  211.              If JOBV = 'V', V contains the P-by-P unitary matrix V.  If JOBV =
  212.              'N', V is not referenced.
  213.  
  214.      LDV     (input) INTEGER
  215.              The leading dimension of the array V. LDV >= max(1,P) if JOBV =
  216.              'V'; LDV >= 1 otherwise.
  217.  
  218.      Q       (output) COMPLEX*16 array, dimension (LDQ,N)
  219.              If JOBQ = 'Q', Q contains the N-by-N unitary matrix Q.  If JOBQ =
  220.              'N', Q is not referenced.
  221.  
  222.      LDQ     (input) INTEGER
  223.              The leading dimension of the array Q. LDQ >= max(1,N) if JOBQ =
  224.              'Q'; LDQ >= 1 otherwise.
  225.  
  226.      WORK    (workspace) COMPLEX*16 array, dimension (max(3*N,M,P)+N)
  227.  
  228.      RWORK   (workspace) DOUBLE PRECISION array, dimension (2*N)
  229.  
  230.      IWORK   (workspace) INTEGER array, dimension (N)
  231.  
  232.      INFO    (output)INTEGER
  233.              = 0:  successful exit.
  234.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  235.              > 0:  if INFO = 1, the Jacobi-type procedure failed to converge.
  236.              For further details, see subroutine ZTGSJA.
  237.  
  238. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  239.      TOLA    DOUBLE PRECISION
  240.              TOLB    DOUBLE PRECISION TOLA and TOLB are the thresholds to
  241.              determine the effective rank of (A',B')'. Generally, they are set
  242.              to TOLA = MAX(M,N)*norm(A)*MAZHEPS, TOLB =
  243.              MAX(P,N)*norm(B)*MAZHEPS.  The size of TOLA and TOLB may affect
  244.              the size of backward errors of the decomposition.
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.